<?php
/**
 * Data provider interface
 *
 * Implementation of this class can be used in user interfaces components that have a dataProvider property.
 */

interface ICollection extends Iterator {
	/**
	 * Applies the specified filter on this collection.
	 * Items that do not pass the specified  filter will be removed.
	 * @param string|array $filter a function, method or equation to be used for filtering
	 * @return ICollection an instance of this object, usefull for chainable methods 
	 */
	public function filter($filter);
	
	/**
	 * Sorts this collection by the specified field either in an ascending or descending order.
	 * @param string $field the name of the field to be sorted
	 * @param string $order the order direction, ASC or DESC
	 * @return ICollection an instance of this object, usefull for chainable methods
	 */
	public function sort($field, $order='ASC');
	
	/**
	 * Removes the items from this collection that do not belong in the sequence as specified by $offset and $length parameters
	 * @param int $offset where the sequence stars
	 * @param int $length the number of items that the sequence should contain
	 * @return ICollection an instance of this object, usefull for chainable methods
	 */
	public function slice($offset, $length);
	
	/**
	 * Returns the item at the position $i
	 * @param int $i the position of item to be returned
	 * @return object the item at position $i
	 */
	public function getItemAt($i);
	
	/**
	 * Returns the value of the specified field at the position $i
	 * @param int $i the position of item to be returned
	 * @param int $field the field
	 * @return object the value of the specified field at the position $i
	 */
	public function getValueAt($i, $field);
	
	/**
	 * Returns the number of items contained in this collection
	 * @return int the number of items contained in this collection
	 */
	public function size();
}
?>